home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / src / demos / VGX / shadows / README < prev    next >
Encoding:
Text File  |  1994-08-02  |  13.0 KB  |  242 lines
  1.  
  2. The programs in this directory illustrate a technique for drawing true
  3. shadows in real-time using the stencil planes of a VGX workstation.  The
  4. technique is described in an article in the November-December, 1991 issue
  5. of IRIS Universe, the text of which is included here in the Showcase file
  6. "Article.showcase", and the figures in the SGI image files "fig1.rgb", etc.
  7. To view the article, execute "showcase Article.showcase".  To see the
  8. figures, execute "ipaste filename".
  9.  
  10. ------------------------------------------------------------------------------
  11. Running the Program
  12. ------------------------------------------------------------------------------
  13.  
  14. If the executables "shadows", "bintoglo", and "glotopdat" are not present,
  15. type "make" to create them.
  16.  
  17. "shadows" demonstrates the technique.  When run without any arguments, it
  18. displays a scene of three cubes lit with a red and a blue point light source.
  19. If the workstation does not have stencil planes, a warning will appear, and
  20. it will be impossible to see stencil mask values or shadows, but the program
  21. will still run.
  22.  
  23. Holding the middle mouse down lets the viewer rotate the scene trackball style.
  24. If the middle mouse button is released while the mouse is moving, the scene
  25. will continue to spin.
  26.  
  27. The left mouse button translates the scene, and the left and middle buttons
  28. held down together track into and out of the scene with the vertical mouse
  29. motion.
  30.  
  31. The right mouse button presents a pop-up menu of several display options.  The
  32. initial mode is "Show Objects Only", in which no shadow calculations are done.
  33.  
  34. "Show Volumes" displays the shadow volume faces projected away from one of the
  35. light sources as semi-transparent surfaces.  This is helpful in understanding
  36. how treating these faces as displayed polygons lets the z-buffer do the work
  37. of shadow-object intersection. In this mode, The silhouette edges of each
  38. object are displayed as solid or dotted yellow lines.  Silhouette edges are
  39. where the surface of an object changes from facing the light source to facing
  40. away from the light source.  The work done in shadow calculation can be
  41. reduced if only those edges are used for the shadow calculation.
  42.  
  43. "Show Mask" displays how the shadow face drawing accumulates to put values
  44. into the stencil planes - clear where no shadow volume faces cover the scene,
  45. magenta at the pixels where you go out of shadow exactly as many times as you
  46. go into it, blue at the pixels where you have gone into shadow once more than
  47. you have gone out, and blue-green where you have gone in two times more than
  48. you have gone out.  In this display mode, the stencil value is accumulated
  49. differently, effectively counting the times gone it and the times gone out,
  50. not just the running total.  As a result, parts of the mask may be displayed
  51. incorrectly or clear due to stencil overflow.  The purpose of this display
  52. mode is to get a feel for what ends up in the stencil planes.
  53.  
  54. "Show Shadows" displays the scene with shadows calculated.  This is done by
  55. drawing the scene once using only the Ambient and Emitted parts for each
  56. object's material description.  These are the components which would determine
  57. the color of the object at a pixel in shadow. Next, the stencil planes are
  58. cleared and each shadow volume face is drawn, incrementing or decrementing a
  59. mask in the stencil planes. Finally, the scene is drawn again using only the
  60. Diffuse and Specular components of each object's material description and the
  61. blendfunction set to (BF_ONE, BF_ONE) so that calculated colors are added to
  62. the colors in the frame buffer.  Since all material components combine
  63. linearly, this gives the same result as if each object had been drawn once
  64. using all its components - Emitted, Ambient, Diffuse, and Specular.  However,
  65. the drawing of the Diffuse and Specular parts is limited to those pixels where
  66. the stencil value is zero, indicating the visible surface there is not in
  67. shadow.
  68.  
  69. "shadows" takes an optional command-line argument specifying a scene
  70. description file to use.  Several examples are included in the directory
  71. "scenes".  These scene files contain references to geometry and texture
  72. files in the "models" and "textures" directory.  To be sure the correct files
  73. are found, always run "shadows" with the current directory set to the directory
  74. which contains the program, e.g.  "./shadows scenes/balls"
  75.  
  76. If the workstation has an accumulation buffer, the positions of the light
  77. sources can be jittered and several images accumulated to produce soft
  78. shadows.  On workstations with an accumulation buffer, an additional menu item
  79. appears, "Turn Soft Shadows On/Off", allowing the jittering to be enabled
  80. or disabled.  To see any effect, the lights in the scene must be defined as
  81. jitterable.  The lights in the default three-cube scene are jitterable and
  82. will produce nice soft shadows.  The default maximum number of frames to
  83. accumulate is 64, but intermediate results will be displayed, and the
  84. maximum value can be changed in a command-line option.
  85.  
  86. Other command-line options allow setting a number of drawing parameters.
  87. These were designed primarily to allow for generation of specific images from
  88. a shell script.  Type "shadows -h" to see all the options.
  89.  
  90.  
  91. ------------------------------------------------------------------------------
  92. File Formats
  93. ------------------------------------------------------------------------------
  94.  
  95. The "shadows" program uses its own file format to describe 3D scenes and
  96. polygonal objects.  By convention, scene description files are identified by
  97. a ".scn" suffix and 3D geometry files by a ".glo" suffix, and both are ASCII
  98. text format.  Textures are stored in SGI image format with a ".rgb" suffix.
  99.  
  100. Models readable by the demo program "flip", identified with a ".bin" suffix,
  101. can be converted into ".glo" format by the program "bintoglo".  This is not a
  102. robust conversion process, but seems to work well in most cases.  A command-
  103. line option, "-f", is provided to reverse the ordering of the vertices of
  104. ".bin" polygons, required in some cases to get front-facing and normal
  105. direction to work out.  The ".bin" file format definitions and read/write
  106. routines are in "fastobj.h" and "fastobj.c".
  107.  
  108. The "shadows" program does a significant amount of processing on the models
  109. to make the shadow face calculation easier, such as keeping edge-adjacency
  110. lists.  When ".glo" files are read into the "shadows" program, all this
  111. processing must happen before any display can occur.  The calculations are
  112. not particularly efficient and for some models this time was getting up around
  113. 30 seconds or so.  To eliminate this problem, a binary format for the
  114. geometry files was created, including all the neat info the "shadows" program
  115. wants.  These files are identified by a ".pdat" suffix.  Routines for reading
  116. and manipulating these files are in "pdat.c".  ".glo" files can be converted
  117. into ".pdat" files with the "glotopdat" utility.
  118.  
  119. All scene information is contained in a ".scn" file.  The first line of the
  120. file must be the single keyword "ShadowScene". Blank lines are ignored and
  121. newlines are treated as blank space.
  122.  
  123. The near and far clipping planes, as well as the height of the viewing frustrum
  124. at the near clipping plane are specified by the WINDOW command.  The LOOKAT
  125. command specifies look-from and look-to points.
  126.  
  127. The MODEL command begins a new object definition and specifies the geometry
  128. file to read.  This file may be either ".glo" or ".pdat" format.  The XMODEL
  129. command is used to define an object which does not cast a shadow, useful for
  130. speeding up complex scenes.
  131.  
  132. After the MODEL command come the optional tranformation, texture, and material
  133. specification. The POSITION, ROTATE, and SCALE commands may appear in any
  134. order, but only the last one of each takes effect, and the transformations
  135. are always done in the order Scale, Rotate, Position, with Rotation done in
  136. the order z, y, x.  The equivalent gl sequence would be
  137.     translate(...);
  138.     rotate(..., 'x');
  139.     rotate(..., 'y');
  140.     rotate(..., 'z');
  141.     scale(...);
  142. Transformation commands which appear before any MODEL command are global
  143. scene transformations, done after individual object transformations.
  144.  
  145. The TEXTURE command specifies the name of an SGI image format file to be used
  146. as a texture.  Currently, all textures are mapped onto the x-z plane in
  147. object space using the texgen command.  The mapping is specified by the
  148. arrays tex_sparams and tex_tparams in "shadows.c".  It is an error for the
  149. TEXTURE command to appear before a MODEL or XMODEL command.
  150.  
  151. The MATERIAL command is followed by a list of one or more specification
  152. commands - SPECULAR, SHININESS, DIFFUSE, EMISSION, or AMBIENT - followed by
  153. the command END.  It is an error for the MATERIAL command to appear before
  154. a MODEL or XMODEL command.  If no material is specified for an object, a
  155. default diffuse gray is assigned.
  156.  
  157. The LIGHT command defines a new light source.  It is followed by a list of
  158. light specification commands - AMBIENT, LCOLOR, POSITION, SPOTDIRECTION,
  159. SPOTLIGHT, JITTER - terminated by the END command.  The commands follow the
  160. semantics of gl light definitions, and JITTER specified the dimensions of
  161. a cube within which the light is given a random position to simulate a
  162. non-point light source when jittering is enabled.  If no lights are specified
  163. for a scene, a red one and a blue one are created.
  164.  
  165. The light model used is defined by the constant theLModel in "shadow_scn.c".
  166. It specifies an ambient value of (0.2, 0.2, 0.2), with local viewer,
  167. attenuation, and two-sided lighting disabled.
  168.  
  169. End-of-file or an END command finishes the scene definition.
  170.  
  171.  
  172. ------------------------------------------------------------------------------
  173. Source Code Modules
  174. ------------------------------------------------------------------------------
  175.  
  176. The main event loop and display code is in "shadows.c".  The main drawing
  177. routine is DrawFrame(), which uses a select statement to implement the proper
  178. drawing mode.  The calculation of shadow volume faces is a fairly
  179. straightforward projection of the edges for a certain distance away from the
  180. light source.  What complicates the technique is allowing the program to
  181. handle non-closed objects.  When shared and non-shared edges appear in the same
  182. object, the into/outof counts can get confused.  To avoid this, the program
  183. always draws its shadow volume faces as closed...
  184.  
  185. The scene reading and setup is done by InitScene() in shadow_scn.c.  It looks
  186. in the global variable sceneFileName to find the name of the ".scn" file to
  187. read.  The scene file contains references to model and texture files, which
  188. are read on demand.  InitScene() then fills in any missing scene description
  189. values, even a complete scene containing 3 cubes and 2 lights if no scene file
  190. is specified.
  191.  
  192. The ".glo" 3D geometry data structure is defined, written, read, and displayed
  193. by defs and routines in "glo_obj.h" and "glo_obj.c".  This is a simple
  194. format for 3D geometry which represents objects as a series of gl bgnpolygon/
  195. v3f/endpolygon calls.  In addition, lmbinds can be interspersed arbitrarily and
  196. objects can be saved without normals, with normal per face, or with normal per
  197. vertex.  Currently only polygons are implemented, with hooks to include lines
  198. and tmeshes.
  199.  
  200. The calculation of edge-adjacency lists and the reading of ".pdat" format
  201. files containing pre-computed information is done by routines in "pdat.c".
  202. The ".pdat" files are binary format and follow the variable formats defined
  203. in "shadows.h".
  204.  
  205. "vect.h" and "vect.c" are useful simple routines for doing math on 3-element
  206. vectors and 4x4 matrices.  These files are slight modifications of the files
  207. found in /usr/people/4Dgifts/examples/trackball.  The files "trackball.h" and
  208. "trackball.c" are exact copies of files found in the same directory and
  209. contain the routines trackball() and build_rotmatrix() used to do quaternion
  210. based rotations.
  211.  
  212.  
  213. ------------------------------------------------------------------------------
  214. Bugs
  215. ------------------------------------------------------------------------------
  216.  
  217. A bug in stencil operation in IRIX 3.x caused all stencil reference values to
  218. be truncated to 4 bits.  Since the "shadows" program uses a value of 128 to
  219. represent a "zero" stencil value in order to allow its ingoing/outgoing count
  220. to go negative, things don't work too well.  To get around this bug in 3.3
  221. systems, change the constant STENZERO in "shadows.c" from 128 to 8.  This will
  222. allow the program to work, though with not as great an in/out range as is
  223. possible with all 8 bits of current VGX hardware under IRIX 4.0.  This change
  224. would also be necessary should SGI make a system with fewer than 8 stencil
  225. planes.  A more robust approach would use getgdesc(GD_BITS_STENCIL) to pick a
  226. zero value.
  227.  
  228. Stray pixels of the wrong shadow value can appear, especially in more complex
  229. images.  I believe this is due to a shared edge of an into/outof shadow
  230. face pair not getting drawn the same way.  Generally drawing shadow faces as
  231. a continuous strip of tmesh avoids any gap or overlap in pixel coverage, but
  232. stencil() commands are not allowed in the middle of a tmesh, so the mesh must
  233. be ended and begun again when switching between drawing into and outof shadow
  234. faces, allowing the possibility of errors.
  235.  
  236. The program does not handle the special case of the viewpoint being in
  237. shadow.
  238.  
  239.  
  240.  
  241. tph, 11/25/91
  242.